Update reference docs to detail universal deletion policy#17445
Update reference docs to detail universal deletion policy#17445NickElliot wants to merge 2 commits intoGoogleCloudPlatform:mainfrom
Conversation
|
Hi there, I'm the Modular magician. I've detected the following information about your changes for commit b06d0a1: Diff reportYour PR hasn't generated any diffs, but I'll let you know if a future commit does. |
melinath
left a comment
melinath
left a comment
There was a problem hiding this comment.
I've left some general stylistic / organizational feedback. I haven't tried actually building the docs & viewing them - I can do that in another round.
|
|
||
| - [`deletion_protection`]({{< ref "/best-practices/deletion-behaviors#deletion_protection" >}}) | ||
| - [`deletion_policy`]({{< ref "/best-practices/deletion-behaviors#deletion_policy" >}}) | ||
| > [!NOTE] |
There was a problem hiding this comment.
rather than have this comment, could we rewrite the examples to be something other than deletion_protection + add a note about deletion_policy fields linking to those docs (assuming they're a separate page)
| title: "Universal Deletion Policy" | ||
| weight: 20 | ||
| --- | ||
| Almost all resources in the provider now support a universal `deletion_policy` field, superceding previous guidance on implementing `deletion_protection` or unique `deletion_policy` fields from [Deletion behaviors]({{< ref "/best-practices/deletion-behaviors" >}}). |
There was a problem hiding this comment.
here and elsewhere: I'd recommend just capturing the current state; we don't need to refer to the previous guidance - or if we do, it should be deprioritized (for example, at the end this page, you could have a "Legacy deletion behaviors" section that summarizes the important points that people need to know for maintaining older fields on resources.)
| @@ -0,0 +1,125 @@ | |||
| --- | |||
| title: "Universal Deletion Policy" | |||
There was a problem hiding this comment.
I'd recommend removing references to "Universal" here & elsewhere (including the filename) - although it's the name of the project, it's probably not important to contributors.
Additionally - this page probably shouldn't be in reference, since it's not a reference - it should either go in develop or best-practices. Personally I'd lean towards replacing best-practices/deletion-behaviors with this content. You don't need to keep that page name, but make sure to add an alias so that references to the old location will redirect.
You'll also want to update the MMv1 resource reference to include the new YAML fields in a reference format (similar to the way other YAML fields are documented on that page.)
|
|
||
| ##Supporting a custom value for deletion_policy | ||
| If implementing support for additional values such as "FORCE", the following steps can be taken. | ||
| A `pre_delete` constant should be added to the `custom_code` block in the resource YAML file, that performs the logic with the corresponding value. Example implemention here: [#1](https://github.com/GoogleCloudPlatform/magic-modules/FEATURE-BRANCH-universal-deletion-policy/mmv1/products/datastream/PrivateConnection.yaml#L44), [#2](https://github.com/GoogleCloudPlatform/magic-modules/blob/FEATURE-BRANCH-universal-deletion-policy/mmv1/templates/terraform/pre_delete/private_connection.go.tmpl) |
There was a problem hiding this comment.
Generally we try to avoid "should": https://developers.google.com/style/prescriptive-documentation#word-choice
I think this might be more clear in active voice as well: https://developers.google.com/style/voice
| A `pre_delete` constant should be added to the `custom_code` block in the resource YAML file, that performs the logic with the corresponding value. Example implemention here: [#1](https://github.com/GoogleCloudPlatform/magic-modules/FEATURE-BRANCH-universal-deletion-policy/mmv1/products/datastream/PrivateConnection.yaml#L44), [#2](https://github.com/GoogleCloudPlatform/magic-modules/blob/FEATURE-BRANCH-universal-deletion-policy/mmv1/templates/terraform/pre_delete/private_connection.go.tmpl) | |
| Add a `pre_delete` constant to the `custom_code` block in the resource YAML file that performs the logic with the corresponding value. Example implemention here: [#1](https://github.com/GoogleCloudPlatform/magic-modules/FEATURE-BRANCH-universal-deletion-policy/mmv1/products/datastream/PrivateConnection.yaml#L44), [#2](https://github.com/GoogleCloudPlatform/magic-modules/blob/FEATURE-BRANCH-universal-deletion-policy/mmv1/templates/terraform/pre_delete/private_connection.go.tmpl) |
Also relevant: https://developers.google.com/style/procedures
This should also be changed in the preceding & following sentences, and maybe elsewhere.
|
|
||
| # Deletion behaviors | ||
| > [!NOTE] | ||
| > **Note:** The guidance on this page has largely been superceded by the implementation of [Universal Deletion Policy]({{< ref "/reference/universal-deletion-policy" >}}). Please refer to that page for details on how to modify the standard implementation of these fields going forward. Any new specifically `deletion_protection` fields should be handled on a case by case basis. |
There was a problem hiding this comment.
rather than having this comment, we should remove this page (or merge it with the deletion policy page as discussed in another comment)
| ##Supporting a custom value for deletion_policy | ||
| If implementing support for additional values such as "FORCE", the following steps can be taken. | ||
| A `pre_delete` constant should be added to the `custom_code` block in the resource YAML file, that performs the logic with the corresponding value. Example implemention here: [#1](https://github.com/GoogleCloudPlatform/magic-modules/FEATURE-BRANCH-universal-deletion-policy/mmv1/products/datastream/PrivateConnection.yaml#L44), [#2](https://github.com/GoogleCloudPlatform/magic-modules/blob/FEATURE-BRANCH-universal-deletion-policy/mmv1/templates/terraform/pre_delete/private_connection.go.tmpl) | ||
|
|
There was a problem hiding this comment.
Maybe it's obvious, but it's important that custom deletion policies should be specifically tested. Since the expectation is that the non-custom ones won't be usually.
4 participants
Release Note Template for Downstream PRs (will be copied)
See Write release notes for guidance.